<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 2. Enabling Transactions</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
    <link rel="up" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
    <link rel="prev" href="perftune-intro.html" title="Performance Tuning" />
    <link rel="next" href="envopen.html" title="Opening a Transactional Environment and Database" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 2. Enabling Transactions</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="enabletxn"></a>Chapter 2. Enabling Transactions</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="enabletxn.html#environments">Environments</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="enabletxn.html#filenaming">File Naming</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="enabletxn.html#errorsupport">Error Support</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="enabletxn.html#sharedmemory">Shared Memory Regions</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="enabletxn.html#security">Security Considerations</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="envopen.html">Opening a Transactional Environment and
            <span>Database</span>
            
            
        </a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
        In order to use transactions with your application, you must turn them
        on. To do this you must: 
  </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
            Use an 
            environment (see <a class="xref" href="enabletxn.html#environments" title="Environments">Environments</a> for details).
        </p>
          </li>
          <li>
            <p>
            Turn on transactions for your environment.

            

            <span>
                You do this by providing the <code class="literal">DB_INIT_TXN</code> 
                flag to the 
                    <code class="methodname">DbEnv::open()</code> 
                     
                method.
            </span>

            <span>
                Note that initializing the transactional subsystem implies that
                the logging subsystem is also initialized. Also, note that
                if you do not initialize transactions when you first create
                your environment, then you cannot use transactions for that
                environment after that. This is because DB
                allocates certain structures needed for transactional
                locking that are not available if the environment is
                created without transactional support.
            </span>
        </p>
          </li>
          <li>
            <p>
            Initialize the in-memory cache by
                <span>
                    passing the <code class="literal">DB_INIT_MPOOL</code>
                flag to the 
                    <code class="methodname">DbEnv::open()</code> 
                     
                method.
                </span>

                
        </p>
          </li>
          <li>
            <p>
            Initialize the locking subsystem. This is what provides locking for concurrent applications. It also is used
            to perform deadlock detection. See <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a>
            for more information.
        </p>
            <p>
            You initialize the locking subsystem by
                <span>
                    passing the <code class="literal">DB_INIT_LOCK</code>
                flag to the 
                    <code class="methodname">DbEnv::open()</code> 
                     
                method.
                </span>

                
        </p>
          </li>
          <li>
            <p>
            Initialize the logging subsystem. While this is enabled by
            default for transactional applications, we suggest that 
            you explicitly initialize it anyway for the purposes of code readability. The logging
            subsystem is what provides your transactional application its durability guarantee, and it is required for
            recoverability purposes. See <a class="xref" href="filemanagement.html" title="Chapter 5. Managing DB Files">Managing DB Files</a>
            for more information.
        </p>
            <p>
            You initialize the logging subsystem by
                <span>
                    passing the <code class="literal">DB_INIT_LOG</code>
                flag to the 
                    <code class="methodname">DbEnv::open()</code> 
                     
                method.
                </span>

                
        </p>
          </li>
          <li>
            <p>
            <span>
                    Transaction-enable your databases. 
            </span>
            <span>
                    If you are using the base API, transaction-enable your databases. 
            </span>
            You do this by
            

            <span>
                encapsulating the database open in a transaction.
            </span>
            

             <span>
             Note that the common practice is for auto commit to be used to
             transaction-protect the database open. To use auto-commit, you
             must still enable transactions as described here, but you do
             not have to explicitly use a transaction when you open your
             database. An example of this is given in the next section.
             </span>
        </p>
          </li>
        </ul>
      </div>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="environments"></a>Environments</h2>
            </div>
          </div>
        </div>
        <div class="toc">
          <dl>
            <dt>
              <span class="sect2">
                <a href="enabletxn.html#filenaming">File Naming</a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="enabletxn.html#errorsupport">Error Support</a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="enabletxn.html#sharedmemory">Shared Memory Regions</a>
              </span>
            </dt>
            <dt>
              <span class="sect2">
                <a href="enabletxn.html#security">Security Considerations</a>
              </span>
            </dt>
          </dl>
        </div>
        <p>
        For simple DB applications, environments are optional. However, in
        order to transaction protect your database operations, you must use an
        environment.
    </p>
        <p>
        An <span class="emphasis"><em>environment</em></span>, represents an
        encapsulation of one or more databases and any associated log and
        region files.  They are used to support multi-threaded 
        and multi-process applications by allowing different threads of
        control to share the in-memory cache, the locking tables, the
        logging subsystem, and the file namespace. By sharing these things,
        your concurrent application is more efficient than if each thread
        of control had to manage these resources on its own.
    </p>
        <p>
        By default all DB databases are backed by files on disk.  In
        addition to these files, transactional DB applications create
        logs that are also by default stored on disk (they can optionally
        be backed using shared memory). Finally, transactional
        DB applications also create and use shared-memory regions that
        are also typically backed by the filesystem. But like databases and
        logs, the regions can be maintained strictly in-memory if your
        application requires it. For an example of an application that
        manages all environment files in-memory, see
            <span><a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.</span>
            
            
            
    </p>
        <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Warning</h3>
          <p>
            Using environments with some journaling filesystems might
            result in log file corruption. This can occur if the operating  
            system experiences an unclean shutdown when a log file is being
            created.  Please see  
            <a href="../../programmer_reference/transapp_journal.html" class="olink">Using
                Recovery on Journaling Filesystems</a>
            
            in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information.
        </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="filenaming"></a>File Naming</h3>
              </div>
            </div>
          </div>
          <p>
            In order to operate, your DB application must be able to
            locate its database files, log files, and region files. If these
            are stored in the filesystem, then you must tell DB where
            they are located (a number of mechanisms exist that allow you to
            identify the location of these files – see below). Otherwise, 
            by default they are located in the current working directory.
        </p>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="envhome"></a>Specifying the Environment Home Directory</h4>
                </div>
              </div>
            </div>
            <p>
                The environment home directory is used to determine where
                DB files are located.  Its location
                is identified using one of the following mechanisms, in the
                following order of priority:
            </p>
            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>
                        If no information is given as to where to put the
                        environment home, then the current working
                        directory is used.
                    </p>
                </li>
                <li>
                  <p>
                    If a home directory is specified on the 
                        
                        <code class="methodname">DbEnv::open()</code>
                        
                    <span>method,</span>
                    
                    then that location is always used for the environment
                    home.
                    </p>
                </li>
                <li>
                  <p>
                        If a home directory is not supplied to 
                         
                        <span><code class="methodname">DbEnv::open()</code>, </span>
                        
                        then the directory identified by the <code class="literal">DB_HOME</code> environment variable
                        is used <span class="emphasis"><em>if</em></span> you specify
                            <span>
                                either the <code class="literal">DB_USE_ENVIRON</code> or
                                <code class="literal">DB_USE_ENVIRON_ROOT</code> flags to the
                                    
                                    <code class="methodname">DbEnv::open()</code>
                                method. Both flags allow you to identify the
                                path to the environment's home directory
                                using the <code class="literal">DB_HOME</code> environment variable. However,
                                <code class="literal">DB_USE_ENVIRON_ROOT</code> is honored only if the
                                process is run with root or administrative privileges.
                             </span>

                            
                    </p>
                </li>
              </ul>
            </div>
          </div>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="filelocation"></a>Specifying File Locations</h4>
                </div>
              </div>
            </div>
            <p>
                By default, all DB files are created relative to the environment
                home directory. For example, suppose your environment home is in 
                    <code class="literal">/export/myAppHome</code>. Also suppose you name your database 
                    <span><code class="literal">data/myDatabase.db</code>.</span>
                    
                Then in this case, the database is placed in:
                    <span><code class="literal">/export/myAppHome/data/myDatabase.db</code>.</span>
                    
            </p>
            <p>
            That said, DB always defers to absolute pathnames.
            This means that if you provide an absolute filename when you 
            name your database, then that file is <span class="emphasis"><em>not</em></span>
            placed relative to the environment home directory. Instead, it
            is placed in the exact location that you specified for the
            filename.
         </p>
            <p>
            On UNIX systems, an absolute pathname is a name that begins with a
            forward slash ('/'). On Windows systems, an absolute pathname is a
            name that begins with one of the following:
        </p>
            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>
                    A backslash ('\').
                </p>
                </li>
                <li>
                  <p>
                    Any alphabetic letter, followed by a colon (':'), followed
                    by a backslash ('\').
                </p>
                </li>
              </ul>
            </div>
            <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>
              <p>
                Try not to use absolute path names for your environment's
                files. Under certain recovery scenarios, absolute path
                names can render your environment unrecoverable. This
                occurs if you are attempting to recover your environment on
                a system that does not support the absolute path name that
                you used.
            </p>
            </div>
          </div>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="splittingdata"></a>Identifying Specific File Locations</h4>
                </div>
              </div>
            </div>
            <p>
                As described in the previous sections, DB will place all its
                files in or relative to the environment home directory.
                You can also cause a
                specific database file to be placed in a particular location by
                using an absolute path name for its name. In this
                situation, the environment's home directory is not
                considered when naming the file.
            </p>
            <p>
                It is frequently desirable to place database, log, and region files on separate
                disk drives. By spreading I/O across multiple drives, you
                can increase parallelism and improve throughput.
                Additionally, by placing log files and database files on
                separate drives, you improve your application's
                reliability by providing your application with a greater
                chance of surviving a disk failure.
            </p>
            <p>
                You can cause DB's files to be placed in specific
                locations using the following mechanisms:
            </p>
            <div class="informaltable">
              <table border="1" width="80%">
                <colgroup>
                  <col />
                  <col />
                </colgroup>
                <thead>
                  <tr>
                    <th>File Type</th>
                    <th>To Override</th>
                  </tr>
                </thead>
                <tbody>
                  <tr>
                    <td>database files</td>
                    <td> 
                                <p>
                                You can cause database files to be created
                                in a directory other than the
                                environment home by using the
                                    
                                    <code class="methodname">DbEnv::add_data_dir()</code>
                                    
                                method.  The directory identified here must
                                exist. If a relative path is provided, then
                                the directory location is resolved relative
                                to the environment's home directory.
                                </p>

                                <p>
                                This method modifies the directory
                                used for database files created and managed by
                                a single environment handle; it does not
                                configure the entire environment. 
                                <span>This
                                method may not be called after the
                                environment has been opened. 
                                </span>
                                </p>
                                
                                <p>
                                You can also set a default data location that is used by
                                the entire environment by using the
                                <code class="literal">add_data_dir</code> parameter
                                in the environment's <code class="literal">DB_CONFIG</code> file.
                                Note that the <code class="literal">add_data_dir</code>
                                parameter overrides any value set by the
                                    
                                    <code class="methodname">DbEnv::set_data_dir()</code>
                                    
                                method.
                                </p>
                            </td>
                  </tr>
                  <tr>
                    <td>Log files</td>
                    <td>
                            <p>
                            You can cause log files to be created
                            in a directory other than the environment home
                            directory by using the
                                    
                                    <code class="methodname">DbEnv::set_lg_dir()</code>
                                    
                                method.  The directory identified
                                here must exist. If a relative path is
                                provided, then the directory location is
                                resolved relative to the environment's home
                                directory.
                             </p>

                             <p>
                                This method modifies the directory
                                used for database files created and managed by
                                a single environment handle; it does not
                                configure the entire environment. 
                                <span>This
                                method may not be called after the
                                environment has been opened. 
                                </span>
                                </p>
                                
                                <p>
                                You can also set a default log file location that is used by
                                the entire environment by using the
                                <code class="literal">set_lg_dir</code> parameter
                                in the environment's <code class="literal">DB_CONFIG</code> file.
                                Note that the <code class="literal">set_lg_dir</code>
                                parameter overrides any value set by the
                                    
                                    <code class="methodname">DbEnv::set_lg_dir()</code>
                                    
                                method.
                                </p>
                            </td>
                  </tr>
                  <tr>
                    <td>Temporary files</td>
                    <td>
                            <p>
                            You can cause temporary files required by the
                            environment to be created
                            in a directory other than the environment home
                            directory by using the
                                    
                                    <code class="methodname">DbEnv::set_tmp_dir()</code>
                                    
                                method.  The directory identified
                                here must exist. If a relative path is
                                provided, then the directory location is
                                resolved relative to the environment's home
                                directory.
                             </p>

                             <p>
                                You can also set a temporary file location 
                                by using the
                                <code class="literal">set_tmp_dir</code> parameter
                                in the environment's <code class="literal">DB_CONFIG</code> file.
                                Note that the <code class="literal">set_tmp_dir</code>
                                parameter overrides any value set by the
                                    
                                    <code class="methodname">DbEnv::set_tmp_dir()</code>
                                    
                                method.
                                </p>
                            </td>
                  </tr>
                  <tr>
                    <td>Metadata files</td>
                    <td>
                            <p>
                            You can cause persistent metadata files required by the
                            replicated applications to be created
                            in a directory other than the environment home
                            directory by using the
                                    
                                    <code class="methodname">DbEnv::set_metadata_dir()</code>
                                    
                                method.  The directory identified
                                here must exist. If a relative path is
                                provided, then the directory location is
                                resolved relative to the environment's home
                                directory.
                             </p>

                             <p>
                                You can also set a metadata directory location 
                                by using the
                                <code class="literal">set_metadata_dir</code> parameter
                                in the environment's <code class="literal">DB_CONFIG</code> file.
                                Note that the <code class="literal">set_metadata_dir</code>
                                parameter overrides any value set by the
                                    
                                    <code class="methodname">DbEnv::set_metadata_dir()</code>
                                    
                                method.
                                </p>
                            </td>
                  </tr>
                  <tr>
                    <td>Region files</td>
                    <td>
                                If backed by the filesystem, region
                                files are always placed in the environment home
                                directory.
                            </td>
                  </tr>
                </tbody>
              </table>
            </div>
            <p>
            Note that the <code class="literal">DB_CONFIG</code> must reside in the
            environment home directory. Parameters are specified in it one
            parameter to a line. Each parameter is followed by a space,
            which is followed by the parameter value. For example:
        </p>
            <pre class="programlisting">    add_data_dir /export1/db/env_data_files </pre>
          </div>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="errorsupport"></a>Error Support</h3>
              </div>
            </div>
          </div>
          <p>
            To simplify error handling and to aid in application debugging, environments offer several useful
            methods. 
            
            <span>Note that many of these
            methods are identical to the error handling methods available for the
            
            <span>Db</span>
            
            
            <span>class.</span>
            
            </span>

            They are:
        </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                <code class="methodname">set_error_stream()</code>
                
            </p>
                <p>
                Sets the
                    <span>C++ <code class="classname">ostream</code></span>
                    
                to be used for displaying error messages issued by the DB library.
            </p>
              </li>
              <li>
                <p>
                <code class="methodname">set_errcall()</code>
                
            </p>
                <p>
                Defines the function that is called when an error message is
                issued by DB. The error prefix and message are passed to
                this callback. It is up to the application to display this
                information correctly.
            </p>
                <p>
                This is the recommended way to get error messages from
                DB.
            </p>
              </li>
              <li>
                <p>
                <code class="methodname">set_errfile()</code>
            </p>
                <p>
                Sets the C library <code class="literal">FILE *</code> to be used for
                displaying error messages issued by the DB library.
            </p>
              </li>
              <li>
                <p>
                <code class="methodname">set_errpfx()</code>
                
            </p>
                <p>
                Sets the prefix used to for any error messages issued by the
                DB library.
            </p>
              </li>
              <li>
                <p>
                <code class="methodname">err()</code>
            </p>
                <p>
                Issues an error message based upon a DB error code a message text that you supply.
                The error message is sent to the
                callback function as defined by <code class="methodname">set_errcall()</code>.
                If that method has not been used, then the error message is sent to the
                file defined by
                    
                    <span>
                        <code class="methodname">set_errfile()</code> or <code class="methodname">set_error_stream()</code>.
                    </span>
                If none of these methods have been used, then the error message is sent to
                standard error.
            </p>
                <p>
                The error message consists of the prefix string
                (as defined by <code class="methodname">set_errprefix()</code>),
                an optional <code class="literal">printf</code>-style formatted message,
                the DB error message associated with the supplied error code, 
                and a trailing newline.
            </p>
              </li>
              <li>
                <p>
                <code class="methodname">errx()</code>
            </p>
                <p>
                Behaves identically to <code class="methodname">err()</code> except
                that you do not provide the DB error code and so 
                the DB message text is not displayed.
            </p>
              </li>
            </ul>
          </div>
          <p>
        In addition, you can use the <code class="function">db_strerror()</code>
        function to directly return the error string that corresponds to a
        particular error number. For more information on the 
        <code class="function">db_strerror()</code> function, see the <code class="literal">Error Returns</code>
        section of the <em class="citetitle">Getting Started with Berkeley DB</em> guide. 
     </p>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3>
              </div>
            </div>
          </div>
          <p>
            The subsystems that you enable for an environment (in our case,
            transaction, logging, locking, and the memory pool)
            are described by one or more regions.  The regions contain all of the
            state information that needs to be shared among threads and/or
            processes using the environment.
        </p>
          <p>
            Regions may be backed by the file system, by heap memory, or by
            system shared memory.
        </p>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4>
                </div>
              </div>
            </div>
            <p>
           By default, shared memory regions are created as files in the environment's
           home directory (<span class="emphasis"><em>not</em></span> the environment's data
           directory). If it is available, the POSIX <code class="literal">mmap</code> 
           interface is used to map these files into your application's
           address space. If <code class="literal">mmap</code> 
           is not available, then the UNIX <code class="literal">shmget</code> interfaces 
           are used instead (again, if they are available).
        </p>
            <p>
            In this default case, the region files are named
            <code class="literal">__db.###</code>
            (for example, <code class="literal">__db.001</code>, <code class="literal">__db.002</code>, 
            and so on).
        </p>
          </div>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4>
                </div>
              </div>
            </div>
            <p>
            If heap memory is used to back your shared memory regions, then
            you can only open a single handle for the environment.  This
            means that the environment cannot be accessed by multiple
            processes.  In this case, the regions are managed only in
            memory, and they are not written to the filesystem. You
            indicate that heap memory is to be used for the region files by
            specifying
                <span>
                    <code class="literal">DB_PRIVATE</code> to the
                    
                    <code class="methodname">DbEnv::open()</code>
                    method.
                </span>

                
        </p>
            <p>
            Note that you can also set this flag by using the
            <code class="literal">set_open_flags</code> parameter in the 
            <code class="literal">DB_CONFIG</code> file. See the 
            <em class="citetitle">Berkeley DB C API Reference Guide</em> for more information.
        </p>
            <p>
            (For an example of an entirely in-memory transactional
            application, see
                <span>
                <a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.)
                </span>
                
                
                
        </p>
          </div>
          <div class="sect3" lang="en" xml:lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h4 class="title"><a id="systembackedregions"></a>Regions Backed by System Memory</h4>
                </div>
              </div>
            </div>
            <p>
            Finally, you can cause system memory to be used for your
            regions instead of memory-mapped files. You do this by providing
                <span>
                    <code class="literal">DB_SYSTEM_MEM</code> to the
                    
                    <code class="methodname">DbEnv::open()</code>
                    method.
                </span>

                
        </p>
            <p>
            When region files are backed by system memory, DB creates a
            single  file in the environment's home directory. This file
            contains information necessary to identify the system shared
            memory in use by the environment. By creating this file, DB
            enables multiple processes to share the environment.
        </p>
            <p>
            The system memory that is used is architecture-dependent. For
            example, on systems supporting X/Open-style shared memory
            interfaces, such as UNIX systems, the <code class="literal">shmget(2)</code>
            and related System V IPC interfaces are used. 
        
            <span> 

                Additionally, VxWorks systems use system memory. In these cases,
                an initial segment ID must be specified by the application to
                ensure that applications do not overwrite each other's
                environments, so that the number of segments created does not
                grow without bounds.  See the 

                    
                    <code class="methodname">DbEnv::set_shm_key()</code>
                    
                method for more information.
            </span>
        </p>
            <p>
            On Windows platforms, the use of system memory for the region files
            is problematic because the operating system uses reference counting
            to clean up shared objects in the paging file automatically. In
            addition, the default access permissions for shared objects are
            different from files, which may cause problems when an environment
            is accessed by multiple processes running as different users. See
                <a class="ulink" href="" target="_top">Windows notes</a>
            or more information.
        </p>
          </div>
        </div>
        <div class="sect2" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a id="security"></a>Security Considerations</h3>
              </div>
            </div>
          </div>
          <p>
            When using environments, there are some security considerations to
            keep in mind:
        </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                    Database environment permissions
                </p>
                <p>
                    The directory used for the environment
                    should have its permissions set to ensure that files in the
                    environment are not accessible to users without appropriate
                    permissions. Applications that add to the user's permissions
                    (for example, UNIX <code class="literal">setuid</code> or
                    <code class="literal">setgid</code> applications), must be
                    carefully checked to not permit illegal use of those
                    permissions such as general file access in the environment
                    directory.
                </p>
              </li>
              <li>
                <p>
                    Environment variables
                </p>
                <p>
                    Setting 

                    <span>
                        the <code class="literal">DB_USE_ENVIRON</code> or
                        <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 
                    </span>
                    

                    so that environment variables can be used during file naming
                    can be dangerous. Setting those flags in DB
                    applications with additional permissions (for example, UNIX
                    <code class="literal">setuid</code> or <code class="literal">setgid</code> 
                    applications) could potentially allow users
                    to read and write databases to which they would not normally
                    have access.
                </p>
                <p>
                    For example, suppose you write a DB application
                    that runs <code class="literal">setuid</code>. This means that
                    when the application runs, it does so under a
                    userid different than that of the application's caller.
                    This is especially problematic if the application is
                    granting stronger privileges to a user than the user
                    might ordinarily have.
                </p>
                <p>
                    Now, if 
                    <span>
                        the <code class="literal">DB_USE_ENVIRON</code> or
                        <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 
                        are set for the environment,
                    </span>
                    
                    
                    
                    then the environment that the application is
                    using is modifiable using the
                    <code class="literal">DB_HOME</code> environment variable. In
                    this scenario, if the uid used by the application has
                    sufficiently broad privileges, then the application's caller
                    can read and/or write databases owned by another user
                    simply by setting his
                    <code class="literal">DB_HOME</code> environment variable to the
                    environment used by that other user.
                </p>
                <p>
                    Note that this scenario need not be malicious; the
                    wrong environment could be used by the application
                    simply by inadvertently specifying the wrong path to 
                    <code class="literal">DB_HOME</code>.
                </p>
                <p>
                    As always, you should use <code class="literal">setuid</code>
                    sparingly, if at all. But if you do use
                    <code class="literal">setuid</code>, then you should refrain from
                    specifying 
                    <span>
                        the <code class="literal">DB_USE_ENVIRON</code> or
                        <code class="literal">DB_USE_ENVIRON_ROOT</code> flags 
                    </span>
                    
                    for the environment open. And, of course, if you must
                    use <code class="literal">setuid</code>, then make sure you use
                    the weakest uid possible – preferably one that is
                    used only by the application itself.
                </p>
              </li>
              <li>
                <p>
                    File permissions
                </p>
                <p>
                    By default, DB always creates database and log files readable and
                    writable by the owner and the group (that is,
                    <code class="literal">S_IRUSR</code>,
                    <code class="literal">S_IWUSR</code>, <code class="literal">S_IRGRP</code> and
                    <code class="literal">S_IWGRP</code>; or octal mode 0660 on historic
                    UNIX systems). The group ownership of created files is based
                    on the system and directory defaults, and is not further
                    specified by DB.
                </p>
              </li>
              <li>
                <p>
                    Temporary backing files
                </p>
                <p>
                    If an unnamed database is created and the cache is too small
                    to hold the database in memory, Berkeley DB will create a
                    temporary physical file to enable it to page the database to
                    disk as needed. In this case, environment variables such as
                    <code class="literal">TMPDIR</code> may be used to specify the
                    location of that temporary file. Although temporary backing
                    files are created readable and writable by the owner only
                    (<code class="literal">S_IRUSR</code> and <code class="literal">S_IWUSR</code>,
                    or octal mode 0600 on historic UNIX systems), some
                    filesystems may not sufficiently protect temporary files
                    created in random directories from improper access. To be
                    absolutely safe, applications storing sensitive data in
                    unnamed databases should use the 
                    
                    <code class="methodname">DbEnv::set_tmp_dir()</code>
                    
                    method to specify a temporary directory with known permissions.
                </p>
              </li>
            </ul>
          </div>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Performance Tuning </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Opening a Transactional Environment and
            <span>Database</span>
            
            
        </td>
        </tr>
      </table>
    </div>
  </body>
</html>
